Release 10.1A: OpenEdge Development:
Progress 4GL Reference

CONTROL-FRAME widget

A control-frame is a field-level widget that holds an ActiveX control that you select for your application from the OpenEdge AppBuilder. A control-frame is always created dynamically.

A control-frame has no visualization.

Progress instantiates two separate but related objects when you create a control-frame:

A control-frame widget.
A control-frame COM object.

The widget itself provides a connection between the ActiveX control and the Progress user interface. When the widget is realized, Progress creates a COM object that provides the real ActiveX control container support. Thus, the control-frame widget provides widget attributes and methods to manage the Progress side of the interface, while the control-frame COM object provides COM object properties and methods to gain access to the control itself.

When you insert an ActiveX control into your application, the AppBuilder creates a control-frame with the CREATE widget statement and specifies a default name (NAME attribute value) for the widget. The AppBuilder creates a design-time instance of the ActiveX control based on the control you select in the AppBuilder, making its design-time properties available to the AppBuilder. When you save your application, the AppBuilder saves the design-time instance in a separate file (with .wrx extension) for use at run time.

At run time, your application accesses the control indirectly through the control-frame widget. First, you use the COM-HANDLE widget attribute to return a component handle to the control-frame COM object. Second, you use this handle to access properties and methods of the control-frame COM object, which provide access to the ActiveX control itself.

This is a SmartViewer into which a developer, using the AppBuilder, has dropped a literal widget, a fill-in widget, and a control-frame widget. The control-frame widget holds a Crescent spin control.

Attributes

Control-frame widget attributes

BGCOLOR attribute1	COLUMN attribute2	COM-HANDLE attribute3
CONTEXT-HELP-ID attribute	DYNAMIC attribute3	FRAME attribute
FRAME-COL attribute3	FRAME-NAME attribute3	FRAME-ROW attribute3
FRAME-X attribute3	FRAME-Y attribute3	HEIGHT-CHARS attribute2
HEIGHT-PIXELS attribute2	HELP attribute	HIDDEN attribute
HTML-CHARSET attribute	NAME attribute2	NEXT-SIBLING attribute3
NEXT-TAB-ITEM attribute3	PARENT attribute	PREV-SIBLING attribute3
PREV-TAB-ITEM attribute3	PRIVATE-DATA attribute	ROW attribute2
SENSITIVE attribute	TAB-POSITION attribute3	TAB-STOP attribute
TYPE attribute3	VISIBLE attribute	WIDGET-ID attribute 4,5
WIDTH-CHARS attribute2	WIDTH-PIXELS attribute2	WINDOW attribute3
X attribute2	Y attribute2
FGCOLOR has no meaning because the ActiveX control visualization constitutes the foreground. Mapped to a corresponding control-frame COM object property. Readable only. Graphical interfaces only. Windows only.

Properties

Control-frame COM object properties¹

Control-Name property2	Controls property	Height property3
Left property3	Name property3	Top property3
Widget-Handle property	Width property3
Accessible using a component handle set to the control-frame COM-HANDLE attribute value. The name of an ActiveX control that is contained by the control-frame COM object. Mapped to a corresponding control-frame widget attribute.

Methods

Control-frame widget methods

ADD-EVENTS-PROCEDURE( ) method	MOVE-AFTER-TAB-ITEM( ) method
MOVE-BEFORE-TAB-ITEM( ) method	MOVE-TO-BOTTOM( ) method
MOVE-TO-TOP( ) method	REMOVE-EVENTS-PROCEDURE( ) method

Control-frame COM object methods¹

LoadControls( ) method
Accessible using a component handle set to the control-frame COM-HANDLE attribute value.

Events

Developer events	BACK-TAB navigation key function event
END-ERROR universal key function event	ENTRY
GO universal key function event	HELP universal key function event
LEAVE	TAB navigation key function event

Notes

You must use the AppBuilder to incorporate one or more ActiveX control instances into a Progress 4GL application. The AppBuilder, operating in design mode, provides the facilities to set design-time properties for ActiveX controls.
After incorporating ActiveX controls into an application with the AppBuilder, the resulting window file, when compiled and executed, interacts with the ActiveX controls at run time.
To access a loaded ActiveX control at run time, use the control-frame COM-HANDLE attribute to get a handle to the control-frame COM object. To return a handle to the control, use the design-time name of the ActiveX control as a property of the control-frame COM object:

DEFINE VARIABLE hCFwid AS WIDGET-HANDLE. /* Control Frame widget */ DEFINE VARIABLE hCFcom AS COM-HANDLE. /* Control Frame COM Object */ DEFINE VARIABLE hDateSpin AS COM-HANDLE. /* ActiveX Control */ /* ... Control-frame created with handle hCFwid and loaded with ActiveX control named DateSpin ... */ hCFcom = hCFwid:COM-HANDLE. hDateSpin = hCFcom:DateSpin.

As an alternative, use the COM object Controls property to return a handle to a control collection. Use the control collection Item(1) method call to return the handle to the ActiveX control. (This control collection object provides support for searching multiple ActiveX controls in a control-frame, available in a future release of OpenEdge.)

You can use a single ActiveX control more than once in a single window file. Each time you insert the control, the AppBuilder creates a separate control-frame for it with a unique NAME attribute value.
Some control-frame widget attributes correspond to control-frame COM object properties so that setting one sets the other. You must directly set and read all ActiveX control run-time properties using a handle (also a COM-HANDLE value) to the control.
To trap control-frame events, use the ON statement, as with any 4GL widget. To trap events for the associated ActiveX control, you must use ActiveX control (OCX) event procedures. Also, to “apply” an ActiveX control event from the 4GL, run the event procedure directly, like any 4GL internal procedure. The APPLY statement has no effect on ActiveX controls. For more information, see the reference entries for the PROCEDURE statement and RUN statement.
Progress control-frame events are mutually exclusive with associated ActiveX control events. That is, only one event handler, either an ON trigger or an event procedure, fires for a single event.

See also

The chapter on ActiveX control container support in OpenEdge Development: Programming Interfaces .